Quarkus Workshop

This workshop should give you a practical introduction to Quarkus. You will first install all the needed tools to then develop an entire microservice architecture, mixing classical HTTP microservices and event-based microservices. You will finish by extending the capabilities of Quarkus and learn more about the ability to create native executables.

The idea is that you leave this workshop with a good understanding of what Quarkus is, what it is not, and how it can help you in your projects. Then, you’ll be prepared to investigate a bit more and, hopefully, contribute.

In this workshop you will develop an application that allows super-heroes to fight against villains. Being a workshop about microservices, you will be developing several microservices communicating either synchronously via REST or asynchronously using Kafka:

The main UI allows you to pick up one random Hero and Villain by clicking on "New Fighters". Then it’s just a matter of clicking on "Fight!" to get them to fight. The table at the bottom shows the list of the previous fights.

You have this material in your hands (either electronically or printed) and you can now follow it step by step. The structure of this workshop is as follow :

If you already have the tools installed, skip the Installing all the needed tools section and jump to the sections Developing with Quarkus and Extending Quarkus, and start hacking some code and addons. This "à la carte" mode allows you to make the most of this 6 hours long hands on lab.

This workshop should be as self explanatory as possible. So your job is to follow the instructions by yourself, do what you are supposed to do, and do not hesitate to ask for any clarification or assistance, that’s why the team is here. Oh, and be ready to have some fun!

First of all, make sure you have Web browser installed on your laptop and internet connectivity. You will also need a GitHub account.

Your environment is remote and can be accessed via CodeReady Workspaces (CRW) through your local browser, you just need to sign up and configure some elements. Your environment includes also Red Hat’s OpenShift Container Platform (OCP).

The next section focuses on how to install and setup the needed software. You can skip the next section if you have already installed all the prerequisites.

CodeReady Workspaces is a collaborative Kubernetes-native development solution that delivers OpenShift workspaces and in-browser IDE for rapid cloud application development. An access to CRW will be provided.

Your lab environment includes Red Hat’s OpenShift Container Platform (OCP).

Access to your OCP resources can be gained via both the oc CLI utility and the OCP web console.

Call to action

First, get the workshop scaffolding by cloning the https://github.com/bbvahackathon/quarkus-super-heroes-workshop repository.

On your CRW terminal:

In this workshop you will be developing an application dealing with Super Heroes (and Super Villains 🦹) as well as Quarkus extensions. The code will be separated into two different directories:

We need to create the 3 databases that we are using. They are described in an OpenShift manifest that can be found under quarkus-super-heroes-workshop/super-heroes/infrastructure/ directory.

As we did for kafka, we will create the DBs using oc utility from the CRW terminal. Make sure that you are authenticated with your USERNAME and you are using the USERNAME-heroes namespace, then apply the databases yaml file:

You can verify the availability of databases with the following command:

You should have the following response:

Now that you have the initial structure in place, we just need configure the correct url for the database.

On your CRW, edit the quarkus-super-heroes-workshop/super-heroes/rest-villain/src/main/resources/application.properties file and the change database configuration:

Change USERNAME with your own.

Now, you can navigate to the root directory and run:

Call to action

By running this command, it downloads all the required dependencies.

Prerequisites has been installed, the different components have been warmed up, it’s now time to write some code!

The easiest way to create a new Quarkus project is to use the Quarkus Maven plugin. We have created the project structure earlier, so we will move to the rest-hero directory and run the project creation command. Open a terminal and run the following command:

Call to action

Once you bootstrap the project, you get the following directory structure with a few Java classes and other artifacts :

The Maven archetype generates the following rest-hero sub-directory:

Once generated, look at the pom.xml. You will find the import of the Quarkus BOM, allowing you to omit the version on the different Quarkus dependencies. In addition, you can see the quarkus-maven-plugin responsible of the packaging of the application and also providing the development mode.

If we focus on the dependencies section, you can see the extension allowing the development of REST applications:

During the project creation, the HeroResource.java file has been created with the following content:

It’s a very simple REST endpoint, returning "hello" to requests on /api/heroes.

Now we are ready to run our application.

Call to action

Use: ./mvnw quarkus:dev:

Then check that the endpoint returns hello as expected:

[source,shell]Now we are ready to run our application

Alternatively, you can open http://localhost:8080/api/heroes in your browser.

quarkus:dev runs Quarkus in development mode. This enables hot deployment with background compilation, which means that when you modify your Java files and/or your resource files and invoke a REST endpoint (i.e. cUrl command or refresh your browser), these changes will automatically take effect. This works too for resource files like the configuration property and HTML files. Refreshing the browser triggers a scan of the workspace, and if any changes are detected, the Java files are recompiled and the application is redeployed; your request is then serviced by the redeployed application. If there are any issues with compilation or deployment an error page will let you know.

The development mode also allows debugging and listens for a debugger on port 5005. If you want to wait for the debugger to attach before running you can pass -Dsuspend=true on the command line. If you don’t want the debugger at all you can use -Ddebug=false.

Alright, time to change some code. Open your favorite IDE and import the project. To check that the hot reload is working, update the method HeroResource.hello() by returning the String "hello hero". Now, execute the cUrl command again, the output has changed without you to having to stop and restart Quarkus:

Call to action

All right, so far so good, but wouldn’t it be better with a few tests, just in case.

In the generated pom.xml file, you can see 2 test dependencies:

Quarkus supports Junit 4 and Junit 5 tests. In the generated project, we use Junit 5. Because of this, the version of the Surefire Maven Plugin must be set, as the default version does not support Junit 5:

We also set the java.util.logging system property to make sure tests will use the correct log manager.

The generated project contains a simple test in HeroResourceTest.java.

By using the QuarkusTest runner, the HeroResourceTest class instructs JUnit to start the application before the tests. Then, the testHelloEndpoint method checks the HTTP response status code and content. Notice that these tests use RestAssured, but feel free to use your favorite library.^[2]

Call to action

Execute it with ./mvnw test or from your IDE. It fails! It’s expected, you changed the output of HeroResource.hello() earlier. Adjust the test body condition accordingly.

Call to action

The application is packaged using ./mvnw package. It produces 2 jar files in /target:

You can run the application using: java -jar target/rest-hero-1.0-SNAPSHOT-runner.jar.

You might come across the following error while developing:

If this is the case, it’s just a matter to add the node name of your machine to the /etc/hosts. For that, first get the name of your node with the following command:

Then sudo vi /etc/hosts so you have the rights to edit the file and add the following entry

In this module we will add extra classes to the Hero API project. You will end-up with the following directory structure:

This microservice:

Hibernate ORM is the de-facto JPA implementation and offers you the full breadth of an Object Relational Mapper. It makes complex mappings possible, but it does not make simple and common mappings trivial. Hibernate ORM with Panache focuses on making your entities trivial and fun to write in Quarkus.^[3]

Because JPA and Bean Validation work well together, we will use Bean Validation to constrain our business model.

To add the required dependencies, just run the following command:

Call to action

This will add the following dependencies in the pom.xml file:

From now on, you can choose to either edit your pom directly or use the quarkus:add-extension command.

Before going further, be sure to run the infrastructure. To execute this service, you need a database (and later on we will need Prometheus and Kafka). Let’s use Docker and docker compose to ease the installation of such infrastructure.

You should already have installed the infrastructure into the infrastructure directory. Now, just execute docker-compose -f docker-compose.yaml up -d. You should see a few logs going on and then all the containers get started.

Call to action

On Linux, use the docker-compose-linux.yaml:

Call to action

To define a Panache entity, simply extend PanacheEntity, annotate it with @Entity and add your columns as public fields (no need to have getters and setters). The Hero entity should look like this:

Notice that you can put all your JPA column annotations and Bean Validation constraint annotations on the public fields.

Quarkus development mode is really useful for applications that mix front end or services and database access. We use quarkus.hibernate-orm.database.generation=drop-and-create in conjunction with import.sql so every change to your app and in particular to your entities, the database schema will be properly recreated and your data (stored in import.sql) will be used to repopulate it from scratch. This is best to perfectly control your environment and works magic with Quarkus live reload mode: your entity changes or any change to your import.sql is immediately picked up and the schema updated without restarting the application!

Call to action

For that, make sure to have the following configuration in your application.properties (located in src/main/resources):

To manipulate the Hero entity we will develop a transactional HeroService class. The idea is to wrap methods modifying the database (e.g. entity.persist()) within a transaction. Marking a CDI bean method @Transactional will do that for you and make that method a transaction boundary.

@Transactional can be used to control transaction boundaries on any CDI bean at the method level or at the class level to ensure every method is transactional. You can control whether and how the transaction is started with parameters on @Transactional:

Call to action

Creates a new HeroService.java file in the same package with the following content:

Notice that both methods that persist and update a hero, pass a Hero object as a parameter. Thanks to the Bean Validation’s @Valid annotation, the Hero object will be checked to see if it’s valid or not. It it’s not, the transaction will be rollback-ed.

Our project now requires a connection to a PostgreSQL database. The main way of obtaining connections to a database is to use a datasource. In Quarkus, the out of the box datasource and connection pooling implementation is Agroal.^[4]

This is done in the src/main/resources/application.properties file.

Call to action

Just add the following datasource configuration:

The HeroResource Endpoint was bootstrapped with only one method hello(). We need to add extra methods that will allow CRUD operations on heroes.

Call to action

Here are the new methods to add to the HeroResource class:

Dependency injection in Quarkus is based on ArC which is a CDI-based dependency injection solution tailored for Quarkus' architecture.^[5] You can learn more about it in the Contexts and Dependency Injection guide.^[6]

ArC comes as a dependency of quarkus-resteasy so you already have it handy. That’s why you were able to use @Inject in the HeroResource to inject a reference to HeroService.

Call to action

To load some SQL statements when Hibernate ORM starts, add the following import.sql in the root of the resources directory. It contains SQL statements terminated by a semicolon. This is useful to have a data set ready for the tests or demos.

Ok, but that’s just a few entries. Download the SQL file import.sql and copy it under src/main/resources. Now, you have around 500 heroes that will be loaded in the database.

If you didn’t yet, start the application in dev mode:

Then, open your browser to http://localhost:8080/api/heroes. You should see lots of heroes…​

To test the HeroResource endpoint, we will be using a QuarkusTestResource that will fire a Postgres database and then test CRUD operations. The QuarkusTestResource is a test extension that can configure the environment before running the application. In our context, we will be using TestContainers to start our database.^[7]

Call to action

For that we will install the TestContainers dependency in our pom.xml as well as some extra test dependencies:

Call to action

Then, you need to create the QuarkusTestResource. Create the io.quarkus.workshop.superheroes.hero.DatabaseResource classes with the following content:

This code just starts the database before the application, and set the quarkus.datasource.url system property to indicate to the application where is the test database. Note that the database would use a random port.

Call to action

Then, in io.quarkus.workshop.superheroes.hero.HeroResourceTest, you will add the following test methods to the HeroResourceTest class:

The code is as follow:

Let’s have a look to the 2 annotations used on the HeroResourceTest class. @QuarkusTest indicates that this test class is checking the behavior of a Quarkus application. The test framework starts the application before the test class and stops it once all the tests have been executed. The tests and the application runs in the same JVM, meaning that the test can be injected with application beans. This feature is very useful to test specific parts of the application. However in our case, we just execute HTTP requests to check the result.

Notice also the @QuarkusTestResource(DatabaseResource.class). It is how the QuarkusTestResource are attached to a test class.

Call to action

With this code written, execute the test using ./mvnw test. The test should pass.

Run time configuration of logging is done through the normal application.properties file.

Because we will end-up running several microservices, let’s configure Quarkus so it listens to a different port than 8080: This is quite easy as we just need to add one property in the application.properties file:

Call to action

Changing the port is one of the rare configuration that cannot be done while the application is running.

Call to action

You would need to restart the application to change the port.

Hit CTRL+C to stop the application and restart it with: ./mvnw quarkus:dev

When we persist a new hero we want to multiply its level by a value that can be configured. For this, Quarkus uses MicroProfile Config to inject the configuration in the application.^[8] The injection uses the @ConfigProperty annotation.

Call to action

Edit the HeroService, and introduce the following configuration properties:

Call to action

Now, modify the HeroService.persistHero() method to use the injected properties:

By default, Quarkus reads application.properties.

Call to action

Edit the src/main/resources/application.properties with the following content:

Call to action

If you didn’t already, start the application with ./mvnw quarkus:dev. Once started, create a new hero with the following cUrl command:

As you can see, we’ve passed a level of 5 to create this new hero. The cUrl command returns the location of the newly created hero. Take this URL and do an HTTP GET on it. You will see that the level has been increased.

Hey! Wait a minute! Tests are failing now! Indeed, they don’t know the multiplier.

Call to action

In the application.properties file, add: %test.level.multiplier=1 which set the multiplier to 1 when running the tests. We will cover the %test syntax soon.

In this module we will add extra class (HeroApplication) to the Hero API project. You will end-up with the following directory structure:

Quarkus proposes a smallrye-openapi extension compliant with the Eclipse MicroProfile OpenAPI specification in order to generate your API OpenAPI v3 specification.^[9]

Call to action

To install the OpenAPI dependency, just run the following command:

This will add the following dependency in the pom.xml file:

Now, you curl http://localhost:8083/openapi endpoint:

This contract lacks of documentation. The Eclipse MicroProfile OpenAPI allows you to customize the methods of your REST endpoint as well as the application.

When building APIs, developers want to test them quickly. Swagger UI is a great tool permitting to visualize and interact with your APIs.^[10] The UI is automatically generated from your OpenAPI specification. The Quarkus smallrye-openapi extension comes with a swagger-ui extension embedding a properly configured Swagger UI page. By default, Swagger UI is accessible at /swagger-ui. So, once your application is started, you can go to http://localhost:8083/swagger-ui and play with your API.

Call to action

You can visualize your API’s operations and schemas.

For example, you can try the /api/heroes/random endpoint to retrieve a random hero.

Call to action

Let’s add a few extra test methods in HeroResourceTest that would make sure OpenAPI and Swagger UI are packaged in the application:

Call to action

Execute the test using ./mvnw test.

In this module we will add an extra class (HeroApplicationLifeCycle) to handle the Hero API lifecycle. You will end-up with the following directory structure:

When our application starts, the logs are pretty boring…​ and lack of a banner (any decent application must have a banner nowadays). So the first thing that you need to do is to go to the following website and pick up your favourite "Hero API" text banner.

Call to action

Create a new class named HeroApplicationLifeCycle (or pick another name, the name does not matter) in the io.quarkus.workshop.superheroes.hero package, and copy your banner so you end up with a similar content:

Thanks to the CDI @Observes, the HeroApplicationLifeCycle is invoked:

Call to action

Run the application with: ./mvnw quarkus:dev, the banner is printed to the console. When the application is stopped, the second log message is printed.

Let’s now produce a native executable for our application. As explained in the introduction of this chapter, Quarkus is able to generate native executables. Just like Go, native executable don’t need a VM to run, they contain the whole application, like an .exe file on Windows.

It improves the startup time of the application, and produces a minimal disk footprint. The executable would have everything to run the application including the "JVM" (shrunk to be just enough to run the application), and the application.

To do so, you will find in the pom.xml the following profile:

Make sure you have the GRAALVM_HOME environment variable defined and pointing to where you installed GraalVM.

Call to action

Then create a native executable using: ./mvnw package -Pnative. In addition to the regular files (rest-hero-1.0-SNAPSHOT.jar and rest-hero-1.0-SNAPSHOT-runner.jar), the build also produces target/rest-hero-1.0-SNAPSHOT-runner (notice that there is no .jar file extension). You can run it using: ./target/rest-hero-1.0-SNAPSHOT-runner.

Producing a native executable can lead to a few issues, and so it’s also a good idea to run some tests against the application running in the native file. In the pom.xml file, the native profile contains:

This instructs the failsafe-maven-plugin to run integration-test and indicates the location of the produced native executable.

Call to action

Then, open the src/test/java/io/quarkus/workshop/superheroes/hero/NativeHeroResourceIT.java and update it with the following:

Instead of using @QuarkusTest, it uses the @NativeImageTest test runner that starts the application from the native file before the tests. The executable is retrieved using the native.image.path system property configured in the Failsafe Maven Plugin.

Also notice that this class also use the @QuarkusTestResource to start and stop the database.

Call to action

To see the NativeHeroResourceIT run against the native executable, use ./mvnw verify -Pnative:

As for the hero microservice, you have the following directory structure:

If you look at the code, it’s very similar to the hero microservice.

Call to action

First, make sure the tests pass by executing the command ./mvnw test (or from your IDE).

Now that the tests are green, we are ready to run our application.

Call to action

Use ./mvnw quarkus:dev to start it (notice the nice banner). Once the application is started, create a new villain with the following cUrl command:

The cUrl command returns the location of the newly created villain. Take this URL and do an HTTP GET on it.

Remember that you can also check Swagger UI by going to http://localhost:8084/swagger-ui.

Like for the Hero and Villain API, the easiest way to create this new Quarkus project is to use a Maven archetype. Under the quarkus-super-heroes-workshop/super-heroes root directory where you have all your code.

Call to action

Open a terminal and run the following command:

Call to action

Also add Testcontainers and other test-related dependencies to your pom.xml.

You can see that beyond the extensions we have used so far, we added the Kafka support which uses Eclipse MicroProfile Reactive Messaging. Stay tuned.

At the end you should have the following directory structure:

A fight is between a hero and a villain. Each time there is a fight, there is a winner and a loser. So the Fight entity is there to store all these fights.

Now comes a trick. The Fight REST API will ultimatelly invoke the Hero and Villain APIs (next sections) to get two random fighters. The Fighters class has one Hero and one Villain. Notice that Fighters is not an entity, it is not persisted in the database, just marshalled and unmarshalled to JSon.

The Fight REST API is just interested in the hero’s name, level, picture and powers (not the other name as described in the Hero API). So the Hero bean looks like this (notice the client subpackage):

Villain is pretty similar (also in the client subpackage):

So, these classes are just used to map the results from the Hero and Villain microservices.

To transactionnally manipulate the Fight entity we need a FightService. Notice the persistFight method. This method is the one creating a fight between a hero and a villain. As you can see the algorithm to determine the winner is a bit random (even though it uses the levels). If you are not happy about the way the fight operates, choose your own winning algorithm ;o)

Call to action

To expose a REST API we also need a FightResource (with OpenAPI annotations of course).

The FightApplication class is just there to customize the OpenAPI contract.

Call to action

To load some SQL statements when Hibernate ORM starts, download the SQL file import.sql and copy it under src/main/resources.

As usual, we need to configure the application.

Call to action

In the application.properties file add:

Note that the fight service uses the port 8082.

We need to test our REST API.

Call to action

For that, copy the following FightResourceTest class under the src/test/java/io/quarkus/workshop/superheroes/fight directory.

You would also need, not only one but 2 QuarkusTestResources, one for the database and one for Kafka. We could have merged both in a single class, but we wanted to illustrate the possibility to have more than one resources.

Call to action

So, create the DatabaseResource class in the same package as the FightResourceTest class, and add the following content:

Call to action

Then, create the KafkaResource class with the following content:

Call to action

Also, delete the generated NativeFightResourceIT class, as we won’t run native test for this microservice.

Call to action

First, make sure the tests pass by executing the command ./mvnw test (or from your IDE).

Now that the tests are green, we are ready to run our application. Use ./mvnw quarkus:dev to start it (notice that there is no banner yet, it will come later). Once the application is started, just check that it returns the fights from the database with the following cUrl command:

Remember that you can also check Swagger UI by going to http://localhost:8082/swagger-ui.

Navigate to the super-heroes/ui-super-heroes/ui-super-heroes directory. It contains the code of the microservice. Being an Angular application, you will find a package.json file which defines all the needed dependencies. Notice that there is a pom.xml file. This is just a convenient way to install NodeJS and NPM so we can build the Angular application with Maven. The pom.xml also allows us to package the Angular application into Quarkus.

If you are not in a frontend mood, just scroll to Installing the Web Application on Quarkus

You don’t need to be an Angular expert, but there are some pieces of code that are worth looking at. If you look under the src/app/shared directory, you will find an api and a model sub-directory. Let’s look at fight.ts.

As you can see, it matches our Fight Java class. Same for fighters.ts, hero.ts or villain.ts. Under api there is the fight.service.ts that defines all the methods to access to our Fight REST API through HTTP.

Well, guess what? We didn’t have to type this code either. It was generated thanks to a tool called swagger-codegen.^[12] Because our Fight REST API exposes an OpenAPI contract, swagger-codegen just swallows it, and generates the TypeScript code to access it. It’s just a matter of running:

Here, you see another advantage of exposing an OpenAPI contract: it documents the API which can be read by a human, or processed by tools.

Thanks to the frontend-maven-plugin plugin declared on the pom.xml, we can use a good old Maven command to install and build this Angular application.

Call to action

Execute mvn install and Maven will download and install Node JS and NPM and build the application. You should now have a node_modules directory with all the Angular dependencies. At this stage, make sure the following commands work:

To install the Angular application into a Quarkus instance, we just build the app and copy the bundles under the resources/META-INF/resources directory. Look at the package.sh, that’s exactly what it does.

Call to action

Execute the package.sh script. You will see all the Javascript files under resources/META-INF/resources directory. We are now ready to go.

Call to action

As usual, use mvn quarkus:dev to start the web application.

Be sure you have the hero and villain microservices running (dev mode is enough).

Once the application is started, go to http://localhost:8080 (8080 is the default Quarkus port as we didn’t change it in the application.properties this time). It should display the main web page.

Oups, not working yet! Not even the pictures, we must have been forgotten something! Let’s move on to the next section then and make the application work.

Remember the structure of the Fight microservice:

We are going to rework the:

Call to action

To install the MicroProfile REST Client dependency, just run the following command:

This will add the following dependency in the pom.xml file:

Remember that in the previous sections we left the FightService.findRandomFighters() method returns null. We have to fix this. What we actually want is to invoke both the Hero and Villain APIs, asking for a random hero and a random villain.

Call to action

For that, replace the findRandomFighters method with the following code to the FightService class:

Note that in addition to the standard CDI @Inject annotation, we also need to use the MicroProfile @RestClient annotation to inject HeroService and VillainService.

Using the MicroProfile REST Client is as simple as creating an interface using the proper JAX-RS and MicroProfile annotations.

Call to action

In our case both interfaces should be created under the client subpackage and have the following content:

The findRandomHero method gives our code the ability to query a random hero from the Hero REST API. The client will handle all the networking and marshalling leaving our code clean of such technical details.

The purpose of the annotations in the code above is the following:

The VillainService is very similar and looks like this:

Call to action

Once created, go back to the FightService class and add the following import statements:

Call to action

In order to determine the base URL to which REST calls will be made, the REST Client uses configuration from application.properties. The name of the property needs to follow a certain convention which is best displayed in the following code:

Having this configuration means that all requests performed using HeroService will use http://localhost:8083 as the base URL. Using this configuration, calling the findRandomHero method of HeroService would result in an HTTP GET request being made to http://localhost:8083/api/heroes/random.

Having this configuration means that the default scope of HeroService will be @Singleton. Supported scope values are @Singleton, @Dependent, @ApplicationScoped and @RequestScoped. The default scope is @Dependent. The default scope can also be defined on the interface.

Now, go back in the UI and refresh, you should see some pictures!

But, now we have another problem. To run the tests of the Fight API we need the Hero and Villain REST APIs to be up and running. To avoid this, we need to Mock the HeroService and VillainService interfaces.

Quarkus supports the use of mock objects using the CDI @Alternative mechanism.^[15]

Call to action

To use this simply override the bean you wish to mock with a class in the src/test/java directory, and put the @Alternative and @Priority(1) annotations on the bean. Alternatively, a convenient io.quarkus.test.Mock stereotype annotation could be used. This built-in stereotype declares @Alternative, @Priority(1) and @Dependent. So, to mock the HeroService interface we just need to implement the following MockHeroService class:

Call to action

Do the same for the MockVillainService:

Call to action

Finally, edit the FightResourceTest and add the following method:

Call to action

First, make sure the tests pass by executing the command ./mvnw test (or from your IDE).

Now that the tests are green, we are ready to run our application. Use ./mvnw compile quarkus:dev to start it. Once the application is started, go to http://localhost:8080 and start fighting (finally !).

To install the MicroProfile Fault Tolerance dependency, just run the following command:

Call to action

This will add the following dependency in the pom.xml file:

Let’s make our find random fighters feature better by providing a fallback way of getting a dummy hero or villain in case of failure.

Call to action

For that, add two fallback methods to the FightService and a @Fallback annotation to both findRandomHero and findRandomVillain methods as follows:

Call to action

Now we are ready to run our application and test the fallbacks.

Call to action

For that, kill the Hero (and/or the Villain API) and start playing again. You should see the following:

Restart the Hero REST API…​ and keep on playing. Super heroes are back to the fight!

Getting random fighters can take longer than expected.

Call to action

To simulate a long running process, update the FightResource with the following code:

Let’s say we’ve added some new functionality in the veryLongProcess method. When the process is really too long and the system is overloaded, we would rather time out.

Call to action

Note that the timeout was configured to 250 ms, and a Thread.sleep was introduced and can be configured in the application.properties. If we set the property to a higher value than the timeout, let’s say 10.000, then the request should be interrupted.

Now that you have set the number of waiting milliseconds to 10.000, run the application and start fighting again. You should see the following:

Call to action

Before going further, set the process.milliseconds to 0.

In this module we will add an extra subdirectory with two classes to handle the Health Check. You will end-up with the following directory structure:

While you could add health checks to all our microservices, we are focusing on the Hero microservice. So don’t forget to switch to the Hero microservice code. You can apply the same to the other microservices.

Call to action

To install the MicroProfile Health dependency, just run the following command:

This will add the following dependency in the pom.xml file:

Importing the smallrye-health extension directly exposes three REST endpoints:

To check that the smallrye-health extension is working as expected, access using your browser or cURL:

All of the health REST endpoints return a simple JSON object with two fields:

The general status of the health check is computed as a logical AND of all the declared health check procedures. The checks array is empty as we have not specified any health check procedure yet so let’s define some.

To check that our Hero API application is live, we can check that the HeroResource.hello() method works.

Call to action

For that, this is the PingHeroResourceHealthCheck class that we can write under the io.quarkus.workshop.superheroes.hero.health sub-package:

As you can see health check procedures are defined as implementations of the HealthCheck interface which are defined as CDI beans with the CDI qualifier @Liveness. The liveness check accessible at /health/live. HealthCheck is a functional interface whose single method call returns a HealthCheckResponse object which can be easily constructed by the fluent builder API shown in the example.

Call to action

As we have started our Quarkus application in dev mode simply repeat the request to http://localhost:8083/health/live by refreshing your browser window or by using curl http://localhost:8083/health/live. Because we defined our health check to be a liveness procedure (with @Liveness qualifier) the new health check procedure is now present in the checks array.

We’ve just created a simple liveness health check procedure which states whether our application is running or not. Here, we will create a readiness health check which will be able to state whether our application is able to process requests.

We will create another health check procedure that accesses our database. If the database can be accessed, then we will always return the response indicating the application is ready.

Call to action

Create the io.quarkus.workshop.superheroes.hero.health.DatabaseConnectionHealthCheck class as follow:

If you now rerun the health check at http://localhost:8083/health/live the checks array will contain only the previously defined PingHeroResourceHealthCheck as it is the only check defined with the @Liveness qualifier. However, if you access http://localhost:8083/health/ready (in the browser or with curl http://localhost:8083/health/ready) you will see only the Database connection health check as it is the only health check defined with the @Readiness qualifier as the readiness health check procedure. If you access http://localhost:8083/health you will get back both checks.

Call to action

Let’s add a few extra test methods that would make sure Health Check are available in the application:

Call to action

To install the MicroProfile Metrics dependency, just run the following command:

This will add the following dependency in the pom.xml file:

We want now to measure all methods of all our REST resources.

Call to action

For that, we need a few annotations to make sure that our desired metrics are calculated over time and can be exported for manual analysis or processing by additional tooling. The metrics that we will gather are these:

Below the source code of the getRandomHero() method, but make sure to add metrics on all methods:

Call to action

Call to action

Let’s add an extra test method that would make sure Metrics are available in the application:

To view the metrics, execute curl -H "Accept: application/json" http://localhost:8083/metrics/application. You will receive a response such as:

Let’s explain the meaning of each metric:

If you prefer an OpenMetrics export rather than the JSON format, remove the -H "Accept: application/json" argument from your command line.

In the super-heroes/load-super-heroes directory, there is an application that is NOT a Quarkus application. It’s a simple Java app that simulates users interacting with the system so it generates some load.

The SuperHeroesLoad class is just a main that executes the FightScenario, HeroScenario and VillainScenario in different threads. For example, if you look at the HeroScenario, you will see that it’s just a suit of HTTP calls on the Hero API:

Call to action

You are all set! Time to compile and start the load application using:

You will see the following logs:

Prometheus needs to be configured to poll data from our microservices. This is made under our infrastructure directory, in the prometheus.yml file:

This file contains basic Prometheus configuration, plus a specific scrape_config which instructs Prometheus to look for application metrics from both Prometheus itself, and our Quarkus microservices at the /metrics endpoint.

The Prometheus console is accessible at http://localhost:9090.

Out of the box, you get a lot of basic JVM metrics or even metrics of Prometheus itself, which are useful. But let’s create new graphs with the metrics of our microservices.

Call to action

Tape timeGetRandomHero in the query, and select application_io_quarkus_workshop_superheroes_hero_HeroResource_timeGetRandomHero_five_min_rate_per_second in the box, and click Execute.

This will fetch the values from our metric showing the number of checks performed:

In this section we are going to extend the Fight microservice. In the following tree, we are going to edit the marked classes

Call to action

To install the Kafka support, just run the following command:

The previous command adds the following dependency:

Then, you can restart the microservice, using mvn compile quarkus:dev.

Call to action

Now edit the FightService class. First, add the following field:

This field is an emitter, and lets you send events or messages (here fights) to the channel specified with the @Channel annotation. A channel is a virtual destination.

In the persistFight method, add the following line just before the return statement:

With this in place, every time the application persists a fight, it also sends the fight to the fights channel.

At this point, the serialized fights are sent to the fights channel. You need to connect this channel to a Kafka topic.

Call to action

For this, edit the application.properties file and add the following properties:

These properties are structured as follows:

For example, mp.messaging.outgoing.fights.connector configures the connector used for the outgoing channel fights.

The mp.messaging.outgoing.fights.value.serializer configures the serializer used to write the message in Kafka. When omitted, the Kafka topic reuses the channel name (fights). Also, it connects by default to localhost:9092. You can override this using the kafka.bootstrap.servers property.

If you go back to the UI and play some fights, you would see, in the fight microservice log, something like:

Now, you have connected the fight microservice to Kafka, and you are sending new fights to the Kafka topic. Let’s see how you can read these messages in the stats microservice.

In this section, we are going to develop the following structure:

Like for the other microservice, the easiest way to create this new Quarkus project is to use a Maven command. Under the quarkus-super-heroes-workshop/super-heroes root directory where you have all your code.

Call to action

Open a terminal and run the following command:

Call to action

Now, create the io.quarkus.workshop.superheroes.statistics.SuperStats class with the following content. This class contains 3 methods annotated with @Incoming and @Outgoing.

The first one (toFightResults) is responsible for deserializing the JSON content received from Kafka. It gets items from the fights channel and produces items sent to the results channel. It takes a Flowable parameter and returns another Flowable. Flowable is a class provided by RX Java 2 and represents a stream of data. So, this method is called only once with a Flowable representing the incoming channel, and the returned Flowable is the outgoing channel. In the body of the method, each item from the incoming channel are mapped to FightResults.

The @Broadcast annotation indicates that several consumers (methods) consume the items produced by the method.

The computeTeamStats method follows the same pattern. It computes the ratio of victories for heroes and villains.

The computeTopWinners method uses more advanced reactive programming constructs such as groupBy, flatMap and scan:

Call to action

In addition, create the io.quarkus.workshop.superheroes.statistics.FightResult, io.quarkus.workshop.superheroes.statistics.Ranking, io.quarkus.workshop.superheroes.statistics.Score and io.quarkus.workshop.superheroes.statistics.TeamStats classes with the following contents:

The FightResult class is used to deserialize the JSON object from the Kafka topic. Note the @RegisterForReflection annotation indicating to Quarkus that this class is accessed using reflection.^[23] This information is required when running the application as a native executable.

Call to action

In FightResult, add or generate the getter and setter methods for the private fields.

Then, create the Ranking class, used to compute a floating top 10, with the following content:

The Score class is a simple structure storing the name of a hero or villain and its actual score, i.e. the number of won battles.

The TeamStats class is an object keeping track of the number of battles won by heroes and villains.

It’s now time to connect the fights channel with the Kafka topic.

Call to action

Edit the application.properties file and add the following content:

As for the writing side, it configures the Kafka connector. The mp.messaging.incoming.fights.auto.offset.reset=earliest property indicates that the topic is read from the earliest available record. Check the Kafka configuration to see all the available settings.

Call to action

Create the io.quarkus.workshop.superheroes.statistics.TeamStatsWebSocket class with the following content:

This component is a WebSocket as specified by the @ServerEndpoint("/stats/team") annotation. It handles the /stats/team WebSocket.

When a client (like a browser) connects to the WebSocket, it keeps track of the session. This session is released when the client disconnects.

The TeamStatsWebSocket also injects a Flowable attached to the team-stats channel. After creation, the component subscribes to this stream and broadcasts the fights to the different clients connected to the web socket.

The subscription is an essential part of the stream lifecycle. It indicates that someone is interested in the items transiting on the stream, and it triggers the emission. In this case, it triggers the connection to Kafka and starts receiving the messages from Kafka. Without it, items would not be emitted.

The io.quarkus.workshop.superheroes.statistics.TopWinnerWebSocket follows the same pattern but subscribes to the winner-stats channel.

Call to action

Creates the io.quarkus.workshop.superheroes.statistics.TopWinnerWebSocket with the following content:

Because the items (top 10) need to be serialized, the TopWinnerWebSocket also use JSONB to transform the object into a serialized form.

Finally, you need a UI to watch these live statistics.

Call to action

Replace the META-INF/resources/index.html file with the following content:

You are all set!

Call to action

Time to start the application using:

Then, open http://localhost:8085 in a new browser window. Trigger some fights, and you should see the live statistics moving.

The first thing to deploy is the required infrastructure:

There are many ways to deploy this infrastructure. Here, we are going to use two operators:

Call to action

With these operators installed, you can create the required infrastructure with the following custom resource definition (CRD):

Call to action

This CRD creates the database for the Hero microservice. Duplicate this CRD for the fight and villain databases.

For the Kafka broker, create the following CRD:

This CRD creates the brokers and the Zookeeper instances.

It’s also recommended to create the topic.

Call to action

For this, create the following CRD:

Once everything is created, you should have the following resources:

Now that the infrastructure is in place, we can deploy our microservices. Let’s start with the hero and villain microservices.

For each, we need to override the port and data source URL.

Call to action

Create a config map with the following content:

Call to action

Do the same for the villain microservice. Then, apply these resources:

Once the config maps are created, we can deploy the microservices.

Call to action

Create a deployment-hero.yaml file with the following content:

This descriptor declares:

The deployment declares one container using the container image we built earlier. It also overrides the configuration for the HTTP port and database URL.

Call to action

Don’t forget to create the equivalent files for the villain microservice.

Then, deploy the microservice with:

Follow the same approach for the fight microservice. Note that there are more properties to configure from the config map:

Once everything is configured and deployed, your system is now running on Kubernetes.